home *** CD-ROM | disk | FTP | other *** search
/ Carousel Volume 2 #1 / carousel.iso / mactosh / da / clipmagi.sit / programming information < prev    next >
Text File  |  1989-06-01  |  7KB  |  126 lines
  1. The Clipboard Magician would look for components in the file 'Magic Wand'.
  2. The components are of the resource type 'CNVT', the resource name must follow
  3. certain naming convention so that CM understands its content. The first four
  4. characters of the resource name is the data type that the component can work on.
  5. So if the scrap data of type 'ICON' is selected, CM would look for all 'CNVT'
  6. resources with names that start with 'ICON' and displayed them to the user.
  7. '****' is used as the wildcard name, so any component with resource name starting
  8. with '****' is always presented to the user if some scrap data type is selected.
  9. '____' is used to indicate null data where no scrap data is selected. This is
  10. for the components that does not need any input data, but would generate new data
  11. on its own. The rest of the resource name is just the name of the component.
  12. THe component that converts one data type to another has a special naming
  13. convention. The resource name would have a '>' as the fifth character,
  14. followed by new data type name. So the component to convert an 'ICON' to 'PICT'
  15. would have the name 'ICON>PICT'.
  16.  
  17. The basic model is that each component is a tool for data transformation, a pipe
  18. where certain type of data goes in at one end, and the transformed data comes
  19. out at the other end. The component is not aware that it is processing scrap data.
  20. In fact the components need not be used in the CM environment. I choose the
  21. CM environment because I want to prove it can be done in a very small program.
  22. It can be a much more powerful system if it is put in a richer environment.
  23. The input to the component is the input data type, the input data handle, and
  24. the component would return the output data type and the output data handle.
  25. The 'CNVT' is just a code resource with the entry point at the beginning.
  26.  
  27. INTERFACE
  28.     TYPE
  29.         RoutineInfo = RECORD
  30.             entryPoint:        ProcPtr;
  31.             resID:            Integer;
  32.             parmCount:        Integer;
  33.             useDefault:        Boolean;
  34.             END;
  35.         RoutineInfoPtr = ^RoutineInfo;
  36.         ParmInfo = RECORD
  37.             srcType:        ResType;
  38.             srcHandle:        Handle;
  39.             dstType:        ResType;
  40.             dstHandle:        Handle;
  41.             { more if necessary }
  42.             END;
  43.         ParmInfoPtr = ^ParmInfo;
  44.         
  45.     FUNCTION ExtRoutine(myInfoPtr: RoutineInfoPtr; parmPtr:parmInfoPtr):OSErr;
  46.     
  47. SrcType and srcHandle is the input to the component. The component returns the
  48. data in dstHandle (initialized to NIL before it is called) and type in dstType.
  49. The function returns NoErr if the conversion is successful, otherwise it
  50. returns an error code. If the operation is successful but no data handle is
  51. generated (as in the case where the component just prints the data), then it
  52. should return a NoErr but leaves the dstHandle as NIL.
  53.  
  54. The RoutineInfo supplies some information that may be useful. ResID is the
  55. resource ID of this code resource. Since a component may need to own resource,
  56. the convention is that an ID range of 32 is assigned to the component. It can
  57. find out its own ID so that it can deduce the ID of the owned resources.
  58.  
  59. ParmCount is the number of parameters in ParmInfo. Right now it is always 4.
  60. It is put here because it may be possible to use the 'CNVT' components in a
  61. non-CM environment, and then it may be possible to have extra parameters. For
  62. example a text printing module may accept extra parameter as the font and size,
  63. and uses default font and size when parmCount = 4 because no extra parameter
  64. is supplied.
  65.  
  66. UseDefault means whether to use the default value or to ask the user about it.
  67. In the CM environment UseDefault is false if the command was evoked with the
  68. option key down. So in the text printing module, if UseDefault is true, the
  69. text is printed with certain font and size, if it is false, a font dialog is
  70. used to let the user choose the value.
  71.  
  72. EntryPoint is the address provided to call other components. If the component
  73. wish to call another component, then it should define the following function
  74.  
  75. Function GoExec(rtnRsrc: ResType; NamePtr:StrintPtr; parmCount:Integer;
  76.                 useDefault:Boolean; parmPtr:Ptr; entryPoint:ProcPtr):
  77.                 OSErr; INLINE $205F, $4E90; {move.l (A7)+, A0; JSR (A0)}
  78.                 
  79. RtnRsrc is the resource type of the component, normally it is 'CNVT'. 
  80. 'CNVT' resource is visible to the user and will be executed by the user,
  81. If you want to write a component that is shared by several components and yet
  82. not visible to the user, you can put them into 'XRTN' resources. 'XRTN'
  83. resource are like 'CNVT' except there is no naming convention and you
  84. decide what the parmaters are. NamePtr is the name of the componet you want
  85. to call. If you are calling a 'CNVT' component, do not forget that there are
  86. four letters in the front. parmCount, useDefault has the usual meaning.
  87. You make up your own parameter list and use parmPtr to point to it. Remember
  88. that if you are calling a XRTN, then the parameter record no longer need to
  89. be of the type ParmInfo, that is why parmPtr is a Ptr rather than a ParmInfoPtr.
  90. entryPoint is just the address provided in routineInfo and GoExec just jsr to it.
  91. Also noted that the call may be to an external routine as well as to an
  92. internal routine since it is up to the dispatcher in CM. However, the current
  93. implementation of CM has no internal call back routine so all calls would be
  94. dispatched to external components.
  95.  
  96. 'CNVT' component may have a resource 'CNV!' with the same ID and the same data
  97. format as 'STR ', the string is a simple description of the component and
  98. will be displayed when the user choose "About this command" from the menu.
  99.  
  100. ******************************************************************************
  101.  
  102. In version 0.55, you may return a data type name 'scrp' which has the same format
  103. as scrap data, i.e. Type name followed by long word data length, followed by the
  104. data padded to even bytes, then the next type etc. The DA would break up the data
  105. and put all of them on to the scrap. Be aware of the fact the specification of the
  106. clipboard magician still need improvement and expect such evolutionary changes in the
  107. future.
  108.  
  109. I have also included a sample program to show how a convertor looks like. For
  110. those of you working with LightSpeed Pascal, I have also include a simulator that
  111. let you dubug a CNVT code resource as an ordinray routine rather than as a code
  112. resource so that you can use all the dubug facilites of LSP. This is like the DA
  113. shell in LSP. In fact all the components release after version 0.5 are written this way.
  114. There are two constants you need to specify for every new CNVT that you are going to
  115. write. The first is the type of data it can handle (resource name/****/____).  If you
  116. intend to use resources you also need to specify the resource base ID.
  117. If you intend to call other code resources you should make a copy of the Magic Wand
  118. and use that file as your resource file in your development process. You may use the
  119. Magic Wand file directly if you do not intend to call up the Clipboard Magican DA
  120. during your debug process. However my own experience is that it is useful to be able
  121. to call up the DA. The simulator is for testing purpose and does not operates like
  122. the DA. Here the components do not work on the data from the scrap directly. The
  123. program maintains a list of data objects (which you can cut/copy/paste to the scrap),
  124. the component will work on the data object selected and the result will be added to
  125. the list of data objects.
  126.